Tutorial for R Markdown and R Notebook

In this presentation, we will give a brief introduction on R Markdown and R Notebooks.

This part of tutorial is adapted from the introduction of R Studio on R Markdown and R Notebooks.

Overview

R Markdown is a text file type that has the extension .Rmd.

It provides a reproducible document framework for data science, and you can use a single R Markdown file to both

• save and execute codes
• generate high quality reports that can be shared with an audience

When you open the R Markdown file in the RStudio IDE, it becomes an R Notebook interface.

R Notebook is an R Markdown document with chunks that can be executed independently and interactively. Any R Markdown document can be used as a notebook, and all R Notebooks can be rendered to other R Markdown document types. A notebook can therefore be thought of as a special execution mode for R Markdown documents.

Creating an R Notebook

You can create a new notebook in RStudio with the menu command File -> New File -> R Notebook, or by using the html_notebook output type in your document’s YAML header.

After that, you will have an R Notebook with one code chunk.

Markdown Basics

Format the text in your R Markdown file with Pandoc’s Markdown, a set of markup annotations for plain text files. When you render your file, Pandoc transforms the marked up text into formatted text in your final file format:

If you prefer to render in “Viewer” Panel instead of a pop-up window. Click on the “wheel” icon that’s next to the “Knit” button, and then choose “Preview in Viewer Pane”.

Table of Content

You might want to include a table of content (TOC) for your report. In fact, a floating table of contents would be especially helpful to the reader when you report becomes lengthy. Below are the arguments for the TOC that you’re seeing at the beginning of this tutorial. More settings for TOC are mentioned here.

---
title: 'Example for TOC'
output:
  html_document:
    toc: true
    toc_depth: 4
---

Table

For displaying data frames and matrixes, knitr::kable would come in handy.

Inserting Chunks

In each chunk, the codes can be executed independently, and the output will appear beneath the chunk.

New chunks can be inserted quickly using the keyboard shortcut Ctrl + Alt + I (OS X: Cmd + Option + I), or via the Add Chunk command in the editor toolbar.

Chunk Options

Chunk output can be customized with knitr options, arguments set in the {} of a chunk header. Above, we use five arguments:

• include = FALSE prevents code and results from appearing in the finished file. R Markdown still runs the code in the chunk, and the results can be used by other chunks.
• echo = FALSE prevents code, but not the results from appearing in the finished file. This is a useful way to embed figures.
• message = FALSE prevents messages that are generated by code from appearing in the finished file.
• warning = FALSE prevents warnings that are generated by code from appearing in the finished.
• fig.cap = "..." adds a caption to graphical results.

Also, you can process many languages in code chunks besides R. Some of the available language engines include:

• Python
• SQL
• Bash
• Stan
• JavaScript

To process a code chunk using an alternate language engine, replace the r at the start of your chunk declaration with the name of the language:

Saving Your R Notebook

When you finish your R Notebook, you can choose to save the .Rmd file. At the same time, an .nb.html file is created alongside it. This file is a self-contained HTML file which contains both a rendered copy of the notebook with all current chunk outputs (suitable for display on a website) and a copy of the notebook .Rmd itself.

Also, the RStudio IDE knit button allows you to render your R Notebook to other formats like .pdf and .docx. You can render to additional formats by clicking the dropdown menu beside the knit button:

Here is how it works:

References

1. R Markdown from R Studio http://rmarkdown.rstudio.com/lesson-1.html

2. R Notebook from R Studio http://rmarkdown.rstudio.com/r_notebooks.html